home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir36 / fpick23a.zip / FPICK.DOC next >
Text File  |  1993-03-29  |  37KB  |  1,012 lines
  1. FPICK                     Version 2.3a               March 29, 1993
  2. ======================================================================
  3. AUTHOR:     Stephen Ferg             
  4.             5113 N. 8th Road
  5.             Arlington, VA 22205-1201
  6.             USA
  7.                          telephone (voice, not FAX): (703) 525-2241
  8.                          CompuServe ID             : 73377,1157
  9. =======================================================================
  10.  
  11.  
  12.  
  13.                              Table of Contents
  14.  
  15. Page numbers in the WordPerfect version of FPICK.DOC (which is not
  16. distributed with FPICK) are lost in the conversion to ASCII format. 
  17. Nevertheless, these page numbers give you a rough idea of the relative
  18. locations of the different sections.
  19.  
  20.   WHAT IS FPICK?. . . . . . . . . . . . . . . . . . . . . . . . . . . .   3
  21.   FPICK PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . .   5
  22.      OVERVIEW OF PARAMETERS . . . . . . . . . . . . . . . . . . . . . .   5
  23.      FILEMASK PARAMETER /M. . . . . . . . . . . . . . . . . . . . . . .   6
  24.      WINDOW COLOR PARAMETER /C. . . . . . . . . . . . . . . . . . . . .   6
  25.      ITEM TYPE PARAMETER /T . . . . . . . . . . . . . . . . . . . . . .   7
  26.      FUNCTION PARAMETER /F and FPICK OUTPUTS. . . . . . . . . . . . . .   8
  27.        FUNCTIONS THAT IMMEDIATELY RETURN RESULTS. . . . . . . . . . . .   9
  28.        FUNCTIONS THAT USE THE PICKLIST WINDOW . . . . . . . . . . . . .  10
  29.        NOTE ON THE "EXT" FUNCTION . . . . . . . . . . . . . . . . . . .  11
  30.      EXCLUDE FILE PARAMETER /X. . . . . . . . . . . . . . . . . . . . .  12
  31.        WARNING ABOUT REDIRECTING FPICK OUTPUT!. . . . . . . . . . . . .  13
  32.      FPICK'S MAXIMUM CAPACITY . . . . . . . . . . . . . . . . . . . . .  14
  33.      HOW TO MOVE FPICK'S CURSOR . . . . . . . . . . . . . . . . . . . .  14
  34.      USING FPICK ON A NETWORK . . . . . . . . . . . . . . . . . . . . .  15
  35.   HOW TO PUT FPICK OUTPUT INTO AN ENVIRONMENT VARIABLE. . . . . . . . .  16
  36.      CALL A BATCH FILE. . . . . . . . . . . . . . . . . . . . . . . . .  16
  37.      USE AN ENVIRONMENT-MANIPULATION UTILITY. . . . . . . . . . . . . .  16
  38.      FPICK'S /V PARAMETER . . . . . . . . . . . . . . . . . . . . . . .  17
  39.      /V WHEN USING 4DOS, NDOS, AND UMB. . . . . . . . . . . . . . . . .  18
  40.   FPICK'S ERROR HANDLING. . . . . . . . . . . . . . . . . . . . . . . .  19
  41.   EXAMPLES OF HOW TO USE FPICK. . . . . . . . . . . . . . . . . . . . .  20
  42.      :01 Display FPICK output on screen . . . . . . . . . . . . . . . .  20
  43.      :02 Redirect FPICK output to a file. . . . . . . . . . . . . . . .  20
  44.      :03 Put FPICK output in an environment variable using a batch file  20
  45.      :04 Put FPICK output in environment variable FPICK using /V parm .  20
  46.      :05 Put FPICK output in environment variable FILE1 using /V parm .  20
  47.      :06 Put FPICK output in an environment variable using STRINGS. . .  20
  48.      :07 Put FPICK output in an environment variable using GET. . . . .  20
  49.      :08 Check FPICK output for unexpected results (version 1). . . . .  21
  50.      :09 Check FPICK output for unexpected results (version 2). . . . .  21
  51.      :11 Pick a .DOC file to browse using LIST. . . . . . . . . . . . .  21
  52.      :12 Save your drive & directory, so you can return to them . . . .  22
  53.      :21 Pop up a picklist of subdirectories. . . . . . . . . . . . . .  22
  54.      :31 How to call FPICK from a REXX program. . . . . . . . . . . . .  23
  55.   DISTRIBUTION ISSUES . . . . . . . . . . . . . . . . . . . . . . . . .  24
  56.      USE, REGISTRATION, AND DISTRIBUTION OF FPICK . . . . . . . . . . .  24
  57.      WHERE TO FIND THE MOST CURRENT VERSION OF FPICK. . . . . . . . . .  25
  58.      UPLOADING FPICK TO ELECTRONIC BULLETIN BOARDS. . . . . . . . . . .  25
  59.      CONTENTS OF THE FPICK.ZIP DISTRIBUTION FILE. . . . . . . . . . . .  25
  60.      FPICK REVISION HISTORY . . . . . . . . . . . . . . . . . . . . . .  25
  61.  
  62.  
  63. WHAT IS FPICK?
  64. ==============
  65.  
  66. FPICK is a utility for providing a file picklist capability in a batch
  67. file.  It displays a list of files whose names conform to a given filemask. 
  68. It then allows a user to scroll through the list using the UParrow,
  69. DOWNarrow, PageUp, and PageDown keys of the keyboard, and to pick a file
  70. from the list by pressing ENTER when the desired filename is highlighted. 
  71. The name of the picked file can be placed into an environment variable,
  72. where it is available for use by subsequent statements in the batch file. 
  73. You can use FPICK to allow a user to pick a file for subsequent editing,
  74. copying, deletion, or browsing.
  75.  
  76. If the user presses ESC when working with the picklist, FPICK's output will
  77. be the 4-character string ":ESC".  Since the character ":" will never occur
  78. as the first character in a valid filename, this output cannot be mistaken
  79. for a filename.
  80.  
  81. If FPICK is unable to find any files that match the filemask, it will
  82. terminate without displaying a picklist, and its output will be the 2-
  83. character string ":0". 
  84.  
  85. You can also have FPICK tell you the number of files or directories that
  86. match a filemask, rather than popping up a picklist.
  87.  
  88. The simplest way to get a feel for what FPICK can do, is to try it.  Copy
  89. the text on the next page into a batch file, and then run it.
  90.  
  91. FPICK is freeware, or what is technically known as "zero-cost shareware". 
  92. There is no requirement to pay for or register FPICK in any way.  For more
  93. details, see the DISTRIBUTION ISSUES section.
  94.  
  95. NOTE
  96. ====
  97.  
  98. The following batch file should run correctly in most environments.  
  99. If it does not, replace the line:
  100.  
  101.      fpick /V
  102.  
  103. with the following three lines:
  104.  
  105.      fpick /P"@set fpick=">junktemp.bat
  106.      call junktemp.bat
  107.      del  junktemp.bat
  108.  
  109. If you have to do this in order to make the batch file work, then look at
  110. the discussion of the /V parameter later in this documentation for an
  111. explanation of the possible reasons.
  112.  
  113.  
  114.  
  115. @echo off
  116. rem ---------------- begin demo batch file ------------------------
  117. cls
  118. REM Give the user instructions on why you want him to pick a file
  119. REM --------------------------------------------------------------
  120. echo Please pick a file whose contents you
  121. echo would like to see TYPE'd to the screen.
  122. echo.
  123. echo I suggest you pick a short text file.
  124. echo.
  125. REM --------------------------------------------------------------
  126. REM Pop up a list of all files that meet the filemask: *.*
  127. REM Put the name of the file the user picks into e-var FPICK
  128. REM --------------------------------------------------------------
  129. fpick /v
  130.  
  131. REM --------------------------------------------------------------
  132. REM If the user pressed ESC, and exited without picking a file,
  133. REM then do no more processing.
  134. REM --------------------------------------------------------------
  135. if (%fpick%)==(:ESC) echo You did not pick a file.
  136. if (%fpick%)==(:ESC) goto endit
  137.  
  138. REM --------------------------------------------------------------
  139. REM The user picked a file.  TYPE it.   
  140. REM --------------------------------------------------------------
  141. echo Ready to type file: %fpick%
  142. pause
  143. cls
  144. type %fpick%
  145.  
  146. :endit
  147. REM Cleanup the environment after yourself: delete the FPICK e-var.
  148. REM --------------------------------------------------------------
  149. set fpick=
  150. rem ---------------- end of demo batch file ------------------------
  151.  
  152. FPICK PARAMETERS
  153. ================
  154.  
  155. All parameters are optional.  If not specified, they all have default
  156. values that are assumed.
  157.  
  158. If the /H parameter or the /? parameter is specified, FPICK displays a help
  159. screen.  
  160.  
  161. Parameters can be in any order and upper or lower case.
  162.      Note that although parms are not case sensitive, they are "text
  163.      sensitive".  If any characters are missing, added, or mistyped, the
  164.      parameter will be rejected.
  165.  
  166.  
  167. OVERVIEW OF PARAMETERS
  168. ======================
  169.  
  170. FPICK /Ffunction   /Mfilemask  /H    /?     /Ttype
  171.       /Vevarname   /Pstring    /Sstring
  172.  
  173.  /F  specifies the FPICK function to perform.
  174.      If omitted, /Ffull is assumed.
  175.  
  176.  /M  specifies a filemask for the files in FPICK's picklist.
  177.      If omitted, *.* is assumed.
  178.  
  179.  /T  specifies type of item (file or directory) to search for.
  180.      If omitted, F (file) is assumed.
  181.  
  182.  /C  specifies background color for picklist window.
  183.      If omitted, C (cyan) is assumed.
  184.  
  185.  /V  If present, this parameter specifies that output is to be placed in an
  186.      environment variable rather than written to standard output.
  187.  
  188.      If /V is specified but not followed by the name of an environment
  189.      variable, then /VFPICK is assumed, and output is placed in the FPICK
  190.      environment variable.
  191.  
  192.  /P  specifies a prefix string for the output.
  193.  /S  specifies a suffix string for the output.
  194.  
  195.      These optional parameters, if specified, must be enclosed in single
  196.      quotes, double quotes, or square brackets.
  197.  
  198.      In these parameters, a group of spaces will be treated as a single
  199.      space, so it is pointless to try to format them by inserting spaces.
  200.  
  201.      The /P feature is useful if you use a batch file to put FPICK's output
  202.      into the environment.  See the discussion of that topic later in this
  203.      documentation.
  204.  
  205. FILEMASK PARAMETER /M
  206. ======================
  207.  
  208. The filemask can contain the standard DOS "*" and "?" wildcards.
  209.  
  210. A filemask can contain disk and path qualifications.  
  211. All of the following are examples of acceptable filemasks:
  212.        /M*.*
  213.        /M*.doc
  214.        /Mmyprog*.*
  215.        /Mbackup?.log
  216.  
  217.        /Mc:\utils\*.doc
  218.        /M\*.doc
  219.        /M..\*.doc
  220.        /M.\*.doc
  221.  
  222.  
  223. Unlike the DOS command processor, FPICK does NOT recognize "." as an
  224. abbreviation for "*.*" in a filemask.
  225.  
  226.        /M*.*   is acceptable
  227.        /M.     is NOT acceptable
  228.  
  229.  
  230. WINDOW COLOR PARAMETER /C
  231. =========================
  232.  
  233. The /C (color) parm controls the background color of the window of FPICK's
  234. picklist.  It must be one letter.  Valid letters and their meanings are:
  235.  
  236. B blue
  237. G green
  238. R red
  239. C cyan
  240. M magenta
  241.  
  242. If the /C parm is not specified, the default value of C (cyan) is used.
  243.  
  244. rem EXAMPLE: show picklist on red background
  245. fpick /v /cR
  246.  
  247.  
  248. ITEM TYPE PARAMETER /T
  249. =========================
  250.  
  251. The /T (type) parm controls whether the picklist displays the names of
  252. files or subdirectories.  Valid letters and their meanings are:
  253.  
  254. F files
  255. D directories
  256.  
  257. Note that if FPICK is asked to gather information on directories, it does
  258. not display, nor count, the names of the current directory (whose name is
  259. ".") and the parent directory (whose name is "..").  
  260.  
  261.      In contrast, DOS's DIR command (when it is run on any directory other
  262.      than the root directory of a disk) does show and count these names. 
  263.      Consequently, if you ask FPICK to count the number of files in a (non-
  264.      root) directory, and the number of subdirectories, and then add the
  265.      two numbers together, the total will be 2 less than the number you get
  266.      from DOS's DIR command.
  267.  
  268. If the /T parm is not specified, the default value of F (files) is used.
  269.  
  270. rem EXAMPLE: show picklist of subdirectories of C:\
  271. fpick /v /mC:\* /tD
  272.  
  273.  
  274.  
  275.  
  276. NOTE 
  277. ====
  278.  
  279. Although it is not customary to give a directory a name that has an
  280. extension, it IS possible to do so under DOS 5.0 (and perhaps with earlier
  281. versions of DOS as well).  
  282.  
  283. I recommend, therefore, that unless you have some specific reason not to do
  284. so, when using the /TD parameter, your filemask parameter (/M) should
  285. always include an extension of "*". 
  286.  
  287. FUNCTION PARAMETER /F and FPICK OUTPUTS
  288. =======================================
  289.  
  290. The /F (function) parameter is used to control the function that FPICK
  291. performs.  The default is "full".  That is, if /F is not specified, the
  292. result is the same as if you had specified the parameter "/Ffull" when
  293. invoking FPICK.
  294.  
  295. Some of FPICK's functions return a result immediately, without popping up a
  296. picklist window.  Others cause a picklist window to pop up, and return a
  297. result based on the filename that the user selects from the list.  
  298.  
  299. The next two subsections discuss:
  300.  
  301.   FUNCTIONS THAT IMMEDIATELY RETURN RESULTS, and 
  302.  
  303.   FUNCTIONS THAT USE THE PICKLIST WINDOW, 
  304.  
  305. respectively.
  306.  
  307.  
  308. FUNCTIONS THAT IMMEDIATELY RETURN RESULTS
  309. -----------------------------------------
  310.  
  311. num    returns the number of files or subdirectories that match filemask.
  312.        returns "0" (zero) if no files or subdirectories match filemask.
  313.  
  314.        If /T parm is /TF (files):
  315.             returns the number of files that match the filemask.
  316.        If /T parm is /TD (directories):
  317.             returns the number of subdirectories that match the filemask.
  318.  
  319.        DISCUSSION
  320.        Before using FPICK to pop up a picklist of filenames, it is often
  321.        wise to use DOS's IF EXIST command to verify that at least one file
  322.        exists to be picked.  Unfortunately, there is no DOS command that
  323.        will allow you to verify that at least one subdirectory exists. 
  324.        FPICK's /FNUM parameter, when used in conjunction with the /TD
  325.        parameter, allows you to gets around this DOS limitation.  Used
  326.        together, /FNUM and /TD will tell you the number of subdirectories
  327.        a directory has.  See EXAMPLES.
  328.  
  329.        Note that if FPICK does not count the current directory (whose name
  330.        is ".") nor the parent directory (whose name is "..").  For any
  331.        directory other than the root directory of a disk, DOS's DIR
  332.        command does show and count these names.  Consequently, if you ask
  333.        FPICK to count the number of files in a non-root directory, and
  334.        then count the number of subdirectories, and then add the two
  335.        numbers together, the total will be 2 less than the number you get
  336.        from DOS's DIR command.
  337.  
  338.        See also: WARNING ABOUT REDIRECTING FPICK OUTPUT
  339.  
  340.  
  341.  
  342. disk   returns the drive letter of the current disk drive, e.g. "C"
  343.  
  344. dir    returns the name of the current directory, e.g. "C:\UTILS"
  345.  
  346.        Note that the output will NEVER have a trailing backslash.
  347.        If you are currently in the root directory of the C drive, the
  348.        result will be "C:"    
  349.  
  350. FUNCTIONS THAT USE THE PICKLIST WINDOW
  351. --------------------------------------
  352.  
  353. These functions pop up a picklist of files (or directories) that meet the
  354. filemask specified on the /M parameter.  In the picklist window, the files
  355. will be sorted alphabetically by filename.
  356.  
  357.  
  358. The picklist window pops up at column 50 (on the right of the screen) and
  359. overwrites anything in the 30 rightmost columns of the screen.  When it
  360. closes, it blacks out the area where it appeared.  Given this behavior, the
  361. best way to use FPICK's picklist window in a batch file is to: 
  362.  
  363.   *  clear the screen (using CLS)
  364.   *  write up to 23 lines of instruction (using ECHO), keeping the lines
  365.      short (no more than about 45 characters)
  366.   *  invoke FPICK
  367.  
  368. For a good example of this sort of coding, look at the DEMO batch file that
  369. appears in the first section of this documentation ("What is FPICK?").
  370.  
  371.  
  372. The picklist window functions return the name of the file picked, in a
  373. format determined by the function specified on the /F parm.
  374.  
  375. The names of the valid picklist functions and their corresponding output
  376. formats is as follows.  The example assumes that the user has picked a file
  377. whose fully-qualified name is: C:\UTILS\TEST.BAT.
  378.  
  379. func   returns                 output
  380. ----   ----------------------  ---------------------------  
  381. full   fully qualified name    C:\UTILS\TEST.BAT
  382. part   path + file prefix      C:\UTILS\TEST
  383. name   filename                TEST.BAT
  384. pre    file prefix             TEST
  385. ext    file extension          BAT
  386.  
  387.  
  388. If the user presses ESC when working with the picklist, FPICK's output will
  389. be the 4-character string ":ESC".  Since the character ":" will never occur
  390. as the first character in a valid filename, this output cannot be mistaken
  391. for a filename.
  392.  
  393. If FPICK is unable to find any files that match the filemask, it will
  394. terminate without displaying a picklist, and its output will be the 2-
  395. character string ":0". 
  396.  
  397.   To avoid having to deal with a possible result of ":0", your batch file
  398.   should test for the existence of files that meet the filemask before
  399.   invoking FPICK.  You can do this using IF NOT EXIST ... GOTO ...
  400.  
  401.  
  402.   EXAMPLE
  403.  
  404.        if not exist c:\*.doc goto NotFound
  405.        FPICK /Mc:\*.doc /V
  406.        if not (%Fpick%)==(:ESC) LIST %Fpick%
  407.        :NotFound
  408.  
  409.  
  410.  
  411.  
  412.  
  413. NOTE ON THE "EXT" FUNCTION
  414. ==========================
  415.  
  416. If you run FPICK with the following parameters:
  417.  
  418.        FPICK /fext /v
  419.  
  420. and the user picks a file whose name has no extension, FPICK's output will
  421. be "" (i.e. the null, or empty, string).  Because assigning the null string
  422. to an environment variable removes it from the environment, the result will
  423. be that the FPICK environment variable will be set to null (i.e. removed
  424. from the environment).
  425.  
  426. EXCLUDE FILE PARAMETER /X
  427. =========================
  428.  
  429. The /X (exclude file) parameter excludes a filename from FPICK's
  430. operations.  
  431.  
  432. /X applies only to files, that is, when /TF has been specified explictly or
  433. by default.  It does not apply to directories, and is ignored if /TD is
  434. specified.
  435.  
  436.  
  437. Example: exclude AUTOEXEC.BAT from FPICK's processing.
  438.        FPICK /Xautoexec.bat
  439.  
  440.  
  441. In a filename specified on the /X parameter, all characters are interpreted
  442. literally.  That is, "?" and "*" are interpreted literally and not as
  443. wildcard characters.  Consequently, wildcard characters should never be
  444. used with /X, since they will never occur in a filename.
  445.  
  446. Since a filename specified using the /X parameter cannot contain wildcards,
  447. only one filename can be excluded from FPICK's processing.
  448.  
  449. For a discussion of the primary use for the /X parameter, see the next
  450. section: WARNING ABOUT REDIRECTING FPICK OUTPUT!
  451.  
  452.  
  453. WARNING ABOUT REDIRECTING FPICK OUTPUT!
  454. =======================================
  455.  
  456. When DOS sees a redirection symbol in a statement, it creates the file that
  457. is the target of redirection BEFORE it executes the statement whose output
  458. is to be redirected.  This pattern of behavior is one of DOS's less
  459. endearing "gotcha's", and one that presents special problems when using
  460. redirection with a program such as FPICK.
  461.  
  462. It may cause FPICK to return an apparently incorrect answer when you
  463. specify the "/FNUM /TF" (or specify simply "/FNUM" and take the default of
  464. "/TF") and redirect FPICK's output.  Suppose you are in a directory that
  465. contains 6 files, and does not contain a file named JUNKTEMP.BAT.  If you
  466. run a batch file containing the following statements:
  467.  
  468.        FPICK /FNUM  /P"@SET FPICK=" >JUNKTEMP.BAT
  469.        call JUNKTEMP.BAT
  470.        del  JUNKTEMP.BAT
  471.  
  472. the result will be that the FPICK environment variable reports a filecount
  473. of 7, not 6.  The reason: The first statement allocates a zero-length file
  474. called JUNKTEMP.BAT before it runs FPICK.  This brings the number of files
  475. in the directory up to 7.  FPICK, when it runs, finds seven files and
  476. returns the correct result of "7".  After JUNKTEMP.BAT is called in the
  477. second statement, it is deleted in the third.  This returns the number of
  478. files in the directory to 6, but leaves the FPICK environment variable
  479. containing the value of "7".
  480.  
  481. Another undesirable side effect of redirection is that the redirected file
  482. may show up on FPICK's picklist.  In the following example, JUNKTEMP.BAT
  483. will show up on the picklist.  
  484.  
  485.        FPICK  /P"@SET FPICK=" >JUNKTEMP.BAT
  486.        call JUNKTEMP.BAT
  487.        del  JUNKTEMP.BAT
  488.  
  489. To get around these problems with redirection, FPICK provides the /X
  490. (exclude file) parameter, which excludes a filename from its operations. To
  491. get the desired result, 6, in the first example, code:
  492.  
  493.        FPICK /FNUM  /Xjunktemp.bat /P"@SET FPICK=" >JUNKTEMP.BAT
  494.        call JUNKTEMP.BAT
  495.        del  JUNKTEMP.BAT
  496.  
  497. To get prevent JUNKTEMP.BAT from appearing on the picklist in the second
  498. example, code:
  499.  
  500.        FPICK  /Xjunktemp.bat /P"@SET FPICK=" >JUNKTEMP.BAT
  501.        call JUNKTEMP.BAT
  502.        del  JUNKTEMP.BAT
  503. FPICK'S MAXIMUM CAPACITY
  504. ========================
  505.  
  506. FPICK is capable of handling up to 1200 files.  Note that if a directory
  507. has several hundred files, it will take FPICK several seconds to count them
  508. or load them into its window.
  509.  
  510. If FPICK has been asked to retrieve more files than it can handle, it will
  511. return an errorlevel of 1, and it will write the following message directly
  512. to the screen.  This message will not be written to standard output, and it
  513. cannot be redirected.
  514.  
  515.      :ERROR: directory contains more files than FPICK can handle.          
  516.              FPICK's upper limit is 1200 files.     
  517.  
  518. If you suspect that you might encounter this error, your batch file can
  519. test for it by using DOS's "IF ERRORLEVEL 1 GOTO ..." statement immediately
  520. after the line that runs FPICK.
  521.  
  522. If there are more than 1200 files in a directory that you want to examine
  523. with FPICK, you can reduce the likelihood of exceeding FPICK's capacity by
  524. specifying a filemask parameter that keeps to a minimum the number of files
  525. that FPICK must retrieve.  The more precise (i.e. restrictive) you can make
  526. the filemask, the better.
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534. HOW TO MOVE FPICK'S CURSOR
  535. ==========================
  536.  
  537. FPICK's cursor is a lightbar that highlights the filename that it is
  538. pointing to.  You can move the cursor up or down in the picklist window by
  539. pressing the up and down arrow keys on your keyboard. 
  540.  
  541. Pressing the PgUp (Page Up) key is the equivalent of pressing the UP arrow
  542. 20 times.  Similarly, pressing the PgDn (Page Down) key is the equivalent
  543. of pressing the DOWN arrow 20 times.  
  544.  
  545. USING FPICK ON A NETWORK
  546. ========================
  547.  
  548. If you are running in a networked environment, FPICK will always be able to
  549. find files in the current directory.  If, however, your filemask indicates
  550. a disk drive, for example:
  551.  
  552.     /Mx:\workdir\*.bat
  553.  
  554. and the disk drive is a network drive, FPICK will not be able to locate
  555. filenames that match that filemask, and FPICK will immediately return ":0".
  556.  
  557. The way to get around this limitation is to change to the desired directory
  558. on the network drive before invoking FPICK, then use a filemask that does
  559. not include a disk drive letter.
  560.  
  561. If you wish, before changing to the network drive, you can use FPICK's
  562. /Fdisk function to obtain and save your current disk drive letter in an
  563. environment variable.  Then, after changing to the desired directory on the
  564. network drive and finishing your work, you can use the environment variable
  565. to return to your original directory.   Here's how to do it in a batch
  566. file:
  567.  
  568. rem save the original drive letter
  569. FPICK /Fdisk /Vdisk
  570.  
  571. rem change to the network drive 
  572. X:
  573. CD \WORKDIR
  574.  
  575. .... do your work ...
  576.  
  577. rem return to your original drive.  (Don't forget the trailing colon :)
  578. %disk%:
  579.  
  580. rem clean up the environment
  581. set disk=
  582.  
  583.  
  584. HOW TO PUT FPICK OUTPUT INTO AN ENVIRONMENT VARIABLE
  585. ====================================================
  586.  
  587.  
  588. CALL A BATCH FILE
  589. =================
  590.  
  591. The most basic way to put FPICK's output into an environment variable is
  592. to:
  593.  
  594.   *  use the /P (prefix string) feature to create a DOS "SET" statement,
  595.   *  redirect the output to a batch file, and then
  596.   *  CALL the batch file.  
  597.  
  598.   Since CALL first appeared in DOS 3.3, you will need DOS 3.3 or greater
  599.   to use this technique.
  600.  
  601.        FPICK /M*.* /XJUNKTEMP.BAT /P"@SET FPICK=" >JUNKTEMP.BAT
  602.        call JUNKTEMP.BAT
  603.        del  JUNKTEMP.BAT
  604.  
  605.  
  606.   See also: WARNING ABOUT REDIRECTING FPICK OUTPUT
  607.  
  608.  
  609.  
  610. USE AN ENVIRONMENT-MANIPULATION UTILITY
  611. =======================================
  612.  
  613.   There are shareware and public domain utilities that are written
  614.   specifically to manipulate environment variables, and do that job very
  615.   well.  FPICK's output can be put into an environment variable by piping
  616.   it to one of these utilities.  When piping FPICK output to a utility,
  617.   you can prevent the output from being ECHOed to the screen by
  618.   redirecting the output to NUL.
  619.  
  620.   Of these utilities, I can especially recommend Bob Stephan's GET
  621.   (because it is a powerful, flexible, and inexpensive shareware package)
  622.   and PC Magazine's STRINGS (because it is free to ZiffNet members).  See
  623.   the EXAMPLES section for examples of how to use STRINGS and GET to put
  624.   FPICK's output into an environment variable.
  625.  
  626.      On CompuServe, use IBMFF to look for GET*.ZIP (e.g. GET25.ZIP for
  627.      version 2.5) in CIS:IBMSYS, or for GET.ZIP in ZNT:UTILFORUM, lib 16. 
  628.      GET is also available from the Public Software Library in Houston.
  629.  
  630.      On CompuServe, look for STRING.ZIP in the PC Magazine Utilities Lib of
  631.      ZNT:UTILFORUM.  
  632.  
  633.  
  634. FPICK'S /V PARAMETER
  635. ====================
  636.  
  637.   FPICK's /V (environment variable) parameter tells FPICK to put its
  638.   output into an environment variable.  (FPICK attempts to put output into
  639.   an environment variable in the master, rather than the local,
  640.   environment.)  If you do not use /V, FPICK output is written to standard
  641.   output, i.e. to the screen.
  642.  
  643.   /Vevar tells FPICK to put output into an environmental variable whose
  644.   name is "evar".  For example:
  645.  
  646.                 FPICK /Mc:\*.bat /Vpicked1
  647.  
  648.   will set the environment variable PICKED1 to the name of the picked
  649.   file.  If you type SET at the DOS prompt, you should see something like:
  650.  
  651.                 PICKED1=C:\AUTOEXEC.BAT
  652.  
  653.   If you specify /V without an evar name, the evar name defaults to FPICK.
  654.  
  655.      Example :       FPICK /Mc:\*.bat /V
  656.      produces:       FPICK=C:\AUTOEXEC.BAT
  657.  
  658.  
  659.  
  660.   Note that due to the complexities of manipulating the environment, there
  661.   may be circumstances where /V doesn't work.  These include running FPICK
  662.   when you have shelled out to DOS from another program, have put the
  663.   command processor in upper memory (UMB) (see below), or are running
  664.   under Windows, Carousel, etc.  In such cases, you may have to fall back
  665.   on one of the more basic techniques (described above) for putting
  666.   FPICK's output into an environment variable.  
  667.  
  668.   For a list of circumstances in which the /V option has been reported as
  669.   NOT working, see the next section.
  670.  
  671. /V WHEN USING 4DOS, NDOS, AND UMB
  672. =================================
  673.  
  674. There are circumstances in which FPICK /V may not be able to set a variable
  675. in the master environment.
  676.  
  677. There are options with 4DOS and NDOS to load the environment and part
  678. of the command processor into upper memory blocks.  When one of these
  679. options is used, FPICK /V can't find the environment and produces the
  680. message:
  681.  
  682.    ERROR
  683.    echo ERROR: Master environment not found
  684.    pause
  685.  
  686. If you have a 4DOS.INI file, it has to contain these lines for FPICK /V
  687. to work:
  688.  
  689.    UMBEnvironment = No
  690.    UMBLoad = No
  691.  
  692. If you have NDOS, the SHELL statement in CONFIG.SYS cannot contain
  693. any reference to UMB loading via /U (which puts NDOS.COM in UMB), nor
  694. can it contain a statement of the form:
  695.                 /E:xxxU
  696. (which puts xxx bytes of the environment in UMB via the "U" parameter).
  697.  
  698. Also, NSTART.BTM or 4START.BTM cannot contain
  699.          SET NDSHELL=/e+xxxU /U
  700. in which both U's represent UMB loading of the command processor and the
  701. environment during secondary shells.
  702.  
  703. It is also possible that FPICK /V may fail to work with MS-DOS if you put
  704. the command processor or the environment in Upper Memory.
  705.  
  706. FPICK'S ERROR HANDLING
  707. ======================
  708.  
  709.    If FPICK detects an error:
  710.  
  711.      (1) it will return an errorlevel of 1 (rather than 0), and
  712.      (2) its output will be 3 lines:
  713.        * the word ERROR
  714.        * a DOS batch-file ECHO statement that displays an error message
  715.        * a DOS batch-file PAUSE statement
  716.  
  717.        The only exception to this behavior is if FPICK is asked to
  718.        retrieve more files than it can handle.  For a description of its
  719.        behavior in such a case, see the section on FPICK'S CAPACITY,
  720.        earlier in this document.
  721.  
  722.    If FPICK output is displayed directly, or redirected to NUL,
  723.    you can detect an error by testing the errorlevel for a value of 1.
  724.  
  725.    If FPICK output is piped to an environment manipulation utility such
  726.    as STRINGS or GET, the environment variable will be set to ERROR.
  727.    Errorlevel will be set by STRINGS/GET, and will probably be 0.
  728.    In such a case, the only way to detect an error is to test the
  729.    environment variable for the value ERROR.
  730.  
  731.    If FPICK output is redirected to a batch file, which is then
  732.    CALLed to set an environment variable, the batch file will:
  733.      * set the environment variable to ERROR,
  734.      * ECHO the error message, and
  735.      * pause.
  736.  
  737.    You can detect an error by testing errorlevel for the value 1
  738.    either before or after you CALL the batch file, or 
  739.    by testing the environment variable for the
  740.    value ERROR, AFTER you have CALLed the batch file.
  741.  
  742.   The kinds of mistakes that cause an FPICK error are invalid parameter
  743.   values, e.g. a misspelled /F parameter, or an invalid letter on the /T
  744.   or /C parameter.  The circumstances when you are most likely to need
  745.   error-checking statements after running FPICK are circumstance in which
  746.   you have obtained the value of an FPICK parameter from an unvalidated
  747.   batch-file parameter:
  748.  
  749.             FPICK /M*.* /C%1 /V
  750.             if errorlevel 1 echo Invalid colorparm [%1] in parameter 1.
  751.             if errorlevel 1 goto endit
  752.  
  753. EXAMPLES OF HOW TO USE FPICK
  754. ============================
  755.  
  756. :01 Display FPICK output on screen
  757. :==================================================================
  758. FPICK /M*.doc 
  759.  
  760.  
  761. :02 Redirect FPICK output to a file
  762. :==================================================================
  763. See also: WARNING ABOUT REDIRECTING FPICK OUTPUT 
  764.  
  765. FPICK /M*.doc >FPICK.OUT
  766.  
  767.  
  768. :03 Put FPICK output in an environment variable using a batch file
  769. :==================================================================
  770. FPICK /M*.doc /P"@SET FPICK=" >JUNKTEMP.BAT
  771. call JUNKTEMP.BAT
  772. del  JUNKTEMP.BAT
  773.  
  774.  
  775. :04 Put FPICK output in environment variable FPICK using /V parm
  776. :==================================================================
  777. FPICK /M*.doc /V
  778.  
  779. :05 Put FPICK output in environment variable FILE1 using /V parm
  780. :==================================================================
  781. FPICK /M*.doc /Vfile1
  782.  
  783.  
  784. :06 Put FPICK output in an environment variable using STRINGS
  785. :==================================================================
  786. FPICK /M*.doc |STRINGS FPICK= ASK >NUL
  787.  
  788.  
  789. :07 Put FPICK output in an environment variable using GET
  790. :==================================================================
  791. FPICK /M*.doc |GET ZE /VFPICK >NUL
  792.  
  793.  
  794. :08 Check FPICK output for unexpected results (version 1)
  795. :==================================================================
  796. @echo off
  797. cls
  798. fpick /m%1 /v
  799. if errorlevel 1 goto endit
  800. for %%v in (:ESC :0) do if (%fpick%)==(%%v) goto %fpick%
  801.  
  802. echo You picked file %fpick%
  803. pause
  804. LIST %fpick%
  805. goto endit
  806.  
  807. :0
  808. echo No files exist that match filemask: %1
  809. goto endit
  810.  
  811. :ESC
  812. echo You did not pick a file.  
  813. goto endit
  814.  
  815. :endit
  816. set fpick=
  817.  
  818.  
  819.  
  820. :09 Check FPICK output for unexpected results (version 2)
  821. :==================================================================
  822. FPICK /M*.doc /v
  823. if errorlevel 1 goto endit
  824. if (%fpick%)==(:0) goto NoneFound
  825. if (%fpick%)==(:ESC) goto NonePicked
  826. ...
  827.  
  828.  
  829.  
  830.  
  831. :11 Pick a .DOC file to browse using LIST
  832. :==================================================================
  833. @echo off
  834. if not exist *.DOC echo There are no .DOC files in this directory.
  835. if not exist *.DOC goto LoopEnd
  836. :LoopTop
  837.   cls
  838.   echo Select the .DOC file you wish to browse.
  839.   Fpick /M*.DOC /V
  840.   cls
  841.   if (%Fpick%)==(:ESC)  goto LoopEnd
  842.   LIST %Fpick%
  843.   goto LoopTop
  844. :LoopEnd
  845. set Fpick=
  846.  
  847. :12 Save your drive & directory, so you can return to them
  848. :==================================================================
  849. rem save the original drive letter
  850. FPICK /Fdisk /Vdisk
  851.  
  852. rem save the original directory spec
  853. FPICK /Fdir /Vdir
  854.  
  855. rem change to the root directory of the same drive
  856. CD \
  857.  
  858. rem change to a different drive
  859. G:
  860.  
  861. .... do your work ...
  862.  
  863. rem return to your original drive.  (Don't forget the trailing colon :)
  864. %disk%:
  865.  
  866. rem return to your original directory
  867. CD %dir%
  868.  
  869. rem clean up the environment
  870. set disk=
  871. set dir=
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878. :21 Pop up a picklist of subdirectories
  879. :==================================================================
  880. @echo off
  881. cls
  882. rem check to see if there are any subdirectories
  883. FPICK /FNUM /TD /V
  884. if (%fpick%)==(0) echo There are no subdirectories in this directory.
  885. if (%fpick%)==(0) goto endit
  886. echo Select the subdirectory to change to.   
  887. Fpick /TD /V
  888. if (%Fpick%)==(:ESC)  goto Endit     
  889. CD %Fpick%  
  890. :Endit
  891. set Fpick=
  892.  
  893.  
  894. :31 How to call FPICK from a REXX program
  895. :==================================================================
  896. Here's how to use FPICK from a REXX program.  I have tested it in
  897. conjunction with Quercus's Personal REXX for DOS, and Kilowatt Software's
  898. Portable REXX for DOS.
  899.  
  900. See also: WARNING ABOUT REDIRECTING FPICK OUTPUT 
  901.  
  902.  
  903. /* use FPICK from a REXX program */
  904. workfile = "JUNKFILE.TMP"
  905.  
  906. "FPICK  /X"workfile" " >"workfile         
  907. choice = linein(workfile)
  908. call lineout workfile   /* close workfile */
  909. "del" workfile
  910.  
  911. /* use CHOICE variable as desired ..... */   
  912.  
  913.  
  914. DISTRIBUTION ISSUES
  915. ===================
  916.  
  917. USE, REGISTRATION, AND DISTRIBUTION OF FPICK
  918. ============================================
  919.  
  920. FPICK is freeware, or what is known as "zero-cost shareware".  FPICK is not
  921. what is technically called "public domain" software because the author
  922. retains the copyright.  FPICK can, however, be copied, used, and
  923. distributed freely as long as FPICK.EXE and FPICK.DOC are not altered and
  924. are distributed together.  
  925.  
  926. There is no requirement to register FPICK in any way.
  927.  
  928. FPICK can be included in shareware packages as long as both FPICK.EXE and
  929. FPICK.DOC are included in the shareware package.
  930.  
  931. If you have received FPICK as part of some larger shareware package,
  932. please be aware that you may freely use, copy, and distribute FPICK
  933. without paying a fee for, or registering, the larger package.
  934.  
  935. The author explicitly disavows any claim whatsoever about the
  936. correctness or functionality of FPICK, its documentation, and its
  937. demonstration batch files, and disclaims liability for anything and
  938. everything bad that might happen in connection with, before, during, or
  939. after using it.  I have tried to make FPICK work right, but everybody
  940. makes mistakes, so you use FPICK at your own risk.
  941.  
  942. I don't know if people will find FPICK useful, and I'd like to find
  943. out.  If you find FPICK useful and use it on a regular basis, I'd
  944. appreciate it if you would drop me a short note via US mail or
  945. CompuServe, telling me about how you are using FPICK.
  946.  
  947.  
  948. WHERE TO FIND THE MOST CURRENT VERSION OF FPICK
  949. ===============================================
  950.  
  951. You will always be able to find the most recent version of FPICK on
  952. CompuServe.  The filename will be FPICK.ZIP, and it will be available
  953. in one of the libraries in the CIS:IBMSYS forum (probably library 1).
  954. You can find it by using cross-library searching, looking for the
  955. filename FPICK.ZIP or the keyword FPICK.
  956.  
  957.  
  958. UPLOADING FPICK TO ELECTRONIC BULLETIN BOARDS
  959. ===============================================
  960.  
  961. Feel free to post copies of FPICK.ZIP on any BBS that you wish, but
  962. please do not upload it to any CompuServe library.  As long as I am the
  963. only one putting copies of FPICK onto CompuServe, we can keep confusion
  964. over versions to a minimum.
  965.  
  966.  
  967. CONTENTS OF THE FPICK.ZIP DISTRIBUTION FILE
  968. ===========================================
  969.  
  970. The current distribution package (FPICK.ZIP) contains the following:
  971.  
  972.        FPICK.EXE         [the FPICK program]
  973.        FPICK.DOC         [this file, documentation for FPICK]
  974.  
  975.  
  976.  
  977.  
  978. FPICK REVISION HISTORY
  979. ======================
  980.  
  981. Letters appended to version numbers indicate modifications to
  982. the doc files, without any modification to the FPICK.EXE software.
  983. Asterisks (*) indicate most important changes in the new version.
  984.  
  985.  
  986. 1.5b Feb 10, 1993
  987.      First public release
  988.  
  989. 1.6a Feb 14, 1993
  990.      Corrected minor bug in which the error message reporting an invalid
  991.      value for the /T parm displayed in bright (rather than regular) white
  992.  
  993. 1.7a Feb 25, 1993
  994.      Added ability to use PageUp and PageDown keys as well as arrow keys
  995.  
  996. 2.0a March 05, 1993
  997.      Increased FPICK capacity to 1200 files from 256
  998.      Added error message if capacity exceeded
  999.  
  1000. 2.1a March 23, 1993
  1001.      Changed internal implementation of NUM function to increase speed
  1002.      Corrected bug that caused /FNUM to return incorrect numbers
  1003.  
  1004. 2.2a March 29, 1993
  1005.      Corrected a bug in which output of /FNUM, /FDISK, and /FDIR was not
  1006.      being written to standard output, and so was not redirectable.
  1007.      
  1008. 2.3a March 29, 1993
  1009.      Added /X parameter
  1010.      Added note: WARNING ABOUT REDIRECTING FPICK OUTPUT
  1011.  
  1012.